Amiga Format CD 6

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Format CD 6 / Amiga Format AFCD06 (Nov 1996, Issue 90).iso / serious / shareware / misc / editkeys / editkeys.doc < prev next >

Wrap

Text File | 1995-10-15 | 24KB | 547 lines

EditKeys v1.63 -------------- © 1991-95 David Kinder ---------------------- Introduction ------------ Around late 1990, I was trying to find a program to allow me to edit the system keymap files. There were a few that let you put strings on keys, but none gave total control over all the features of keymaps. So I decided to write my own editor. I mean, how hard could it be..? The result is EditKeys, a keymap editing program designed to work under AmigaDOS 1.3 and higher. EditKeys is written in machine code and compiled using HiSoft's Devpac v3 assembler, though it should not be that difficult to compile under other assemblers. EditKeys is freely distributable, provided that no more is charged than a nominal fee for copying and disk media. If you want to use a keymap created with EditKeys in a PD or commercial package then the only condition I impose is that I receive a credit somewhere in the program or its documentation. Files ----- Program - EditKeys EditKeys.info Documentation - EditKeys.doc Disk Libraries - arp.library (must be in LIBS: for AmigaDOS 1.3) asl.library (must be in LIBS: for AmigaDOS 2.0+) Source files - EditKeys.s Graphics.s xdef.i xref.i Tech.Notes About EditKeys -------------- EditKeys allows you to edit or create keymap files (They are found in the Devs/Keymaps/ directory of the boot disk). If you don't know about these files, then perhaps I should explain. When you press a key on the Amiga's keyboard, the key press is translated by the keymap file that the system is using. For instance, British Amigas use the keymap 'gb'. Different keymaps can be found on the system disks supplied with your Amiga. They are found in: AmigaDOS 1.3 Extras1.3:Devs/keymaps/ AmigaDOS 2.0 Extras2.0:Devs/Keymaps/ AmigaDOS 3.0 Storage3.0:Keymaps/ Under AmigaDOS 2.1 and higher keymaps have icons, and are loaded into the system with the Input prefs editor (or the SetKeyboard command). With earlier releases, keymaps are loaded with the SetMap program, found in the System drawer of the boot disk. If you load a keymap different to your native one, you will find typing some keys gives unexpected results (especially the non-alphanumeric keys (eg. [,;,# )). Keymaps can be changed to give more radical results; you could redefine the numerical keypad to produce alphabetic characters if you wanted to, or you can configure keys to output strings (useful for disk-menus etc.). Please note that any changes made using EditKeys do NOT come into effect until you load the keymap via the system software; only when you select 'Save' in EditKeys is a suitable keymap structure constructed and saved to disk so that AmigaDOS can use it. Keymap Specifications --------------------- At this point, perhaps I should define some of the terms I will use: Qualifier Key - CTRL, ALT or SHIFT keys. Do not produce output on their own but qualify the output of other keys (eg Shift-f produces 'F'). Physical Key - An actual key on the keyboard, the thing that you touch when you type. Key - A combination of a physical key and a qualifier, eg q is a key, as is Shift-q, Alt-q, Shift-Alt-q, etc. Note that Alt-q is an abreiviation for holding down the ALT key while tapping the 'q' key. Keymaps contain quite a lot of information, none of which appears in the user manuals but appears in the RKM under 'console.device' (Makes sense to put info about the keyboard in a programmer's manual eh?). Therefore I shall attempt to briefly describe what is possible. Keys can be redefined to produce any character when pressed with one of the qualifiers, and also keys can produce strings of up to 32 characters. Physical keys with a STRING key on them may not have DEAD or MODIFIABLE keys on them (see below). Some keys repeat when held down (eg all alphabetic keys), while others do not (eg the <RETURN> key). Physical keys which repeat are referred to as REPEATABLE (fairly obvious). Whether a key repeats or not is controlled by the keymap. Similarly, the keymap controls whether a key is CAPSABLE or not. When the 'Caps Lock' light is on, some keys produce their Shifted values (eg 'q'), while the numerical keys produce their normal values. Some keys are DEAD, while others are MODIFIABLE. For an example of this, open a CLI window, then hold down ALT while tapping the 'f' key (From now on abrieviated to Alt-f); nothing happens. Now tap the 'a' key, the result is an a with an accent over it: 'á'. The key Alt-f is a DEAD key, while 'a' is a MODIFIABLE key. When you type Alt-f, the Amiga stores the deadkey, which it then uses to modify the output of the 'a' key. Not all keys are MODIFIABLE, Alt-f followed by 'q' just produces 'q'. A physical key with DEAD or MODIFIABLE keys on it may NOT have STRING keys on it. There is a further limitation in that those physical keys that are not DEAD or MODIFIABLE use only 4 bytes for their definition, eg on the 'A' key on your keyboard there is 'a', 'A', 'æ' and 'Æ'. However, there are 8 different permutations of the Shift, Alt and Control qualifiers with the key, so not every combination of physical key with qualifier can be uniquely defined. Why didn't Commodore use 8 bytes for each key? (sigh). There is one other point; if a physical key has definitions for Shift and Alt (and thus Shift-Alt) then we can configure the key so that the Control qualifier outputs the value that would appear without the Control key being pressed, but with bits 6 and 7 cleared (eg Control-c). Confused? You're not the only one... But playing around with EditKeys should make all this clear (or at least clearer than it is at present). It is worth noting before I start on a discussion of EditKeys that once you have loaded a keymap into the system, you cannot replace it with another of the same name using SetMap or SetKeyboard. This is because the system expects keymaps not to change. The solution to this is to use the supplied 'LoadKeymap' command. The Program ----------- EditKeys allows you to modify all the above features of a keymap. Keys may be made DEAD or MODIFIABLE, or have STRING definitions put on them, as well as being redefined. The program may be started from CLI or Workbench: From Workbench: Just double click on the program's icon. A file requester will appear for you to select a keymap to load. Click on a keymap or 'Cancel'. From CLI: 1) Just type the program's name, ie 1> EditKeys The program will attempt to display a file requester prompting you for a keymap to load. Select a keymap or click on 'Cancel' to start the program without a keymap loaded. Or, 2) Pass a keymap name to the program, ie. EditKeys [<keymap>] [NOMAP] eg 1> EditKeys gb or 1> EditKeys NOMAP You do not need to specify the path of the keymap as EditKeys will automatically look in DEVS:keymaps/. If you specify the NOMAP option then EditKeys will start without loading a keymap. Or, 3) Enter the line 1> EditKeys ? Which will bring up a template. Entering a further ? will prompt you with a small help message. Enter a keymap name or NOMAP (see above). When the program has loaded it will open a window on the Workbench screen. In the titlebar is the name of the keymap being edited; below that is a representation of the A500/A2000/A1200 keyboard with the keymap you chose. Note that it may appear to you that the keyboard has acquired two extra keys (one to the right of the left Shift key and the other to the left of the Return key), as these are not present on the older UK and US Amigas. Furthermore, the representation of the keymap usually shows what is output by that key, but for certain keys (eg Esc, Help, Del, F1-F10) I have chosen to use a little graphic which never changes as this looks better. If you need to be certain what a key outputs, click on it; its output will be displayed at the bottom to the EditKeys window. Qualifier keys (Shift etc.) displayed on the screen work as expected; click on Shift to see the effect. The program is run using the menus and the five mode gadgets displayed below the keyboard; each gadget represents a different aspect of the keymap that can be edited. To choose a mode, simply click on its gadget. The five modes are: Keymap - Used to (re)define output of any key Capsable - Used to determine which keys are capsable Repeatable - Used to determine which keys repeat Modifiable - Used to define which keys are modifiable Deadkeys - Used to define dead keys I will deal with these sections in increasing order of complexity. Capsable -------- As explained above, physical keys can be CAPSABLE or not, and this mode lets you set this function for each physical key. If the key is highlighed then that key is capsable; if it is not then the physical key isn't. The qualifier gadgets are ghosted as they serve no purpose in this mode. Simply click on a key with the mouse to change it's state. Repeatable ---------- Basically the same as the above Capsable mode, except that this mode is used to control which keys are REPEATABLE or not. Works in exactly the same way as above. Deadkeys -------- As expained above, keymaps can contain DEAD keys, and this mode allows you to set them. Click on a key to make it dead or turn it back to normal. Deadkeys don't do anything immediately when pressed; thus when you turn a dead back to normal the key is blank. Since each particular key can be DEAD or not, the qualifiers are active. If you make a key dead, and the physical key that key is on already has another deadkey, then you can make the second deadkey act in the same way as the first. This isn't too useful, but it's implemented in the CBM keymaps, so here it is. Deadkey definitions are stored within the keymap in a completely diffent way to ordinary keys, so if a physical key has deadkeys on it, then it can be defined for any combination of qualifiers. As expained earlier, this is not so for ordinary keys. If you turn a deadkey back to normal and it is the last deadkey on that physical key, EditKeys will try to resolve this without destroying any definitions; but if it can't a requester will appear asking you which definitions you want to get rid of. As a general rule the least useful set of definitions are those with the Control qualifier, so I'd remove these first if I were you, but it's your choice. As also explained above, if a normal key has definitions for Shift, Alt and Shift-Alt, then the Control key may have a special effect on it - it may clear bits 6&7 of the normaly output character (eg if you enter Control-c in the string gadget, you get a capital C in reverse (try it and see)). If it is possible to do this with the key as we convert it from dead to normal, a requester will appear asking whether you want this feature or not (As a general rule, in the CBM supplied keymaps it is turned on for most alphabetic keys). You can have a maximum of 15 deadkeys, a limitation imposed by the keymap, not me. 15 should be enough anyway. If you define 15 diffent deadkeys then all non-dead keys will be ghosted as no more can be defined. Turn a deadkey back to a normal key to de-ghost all the other keys. Physical keys with STRING keys on them cannot also have DEAD keys on them; thus all string keys are ghosted and unselectable. Physical keys with MODIFIABLE keys on them may also have DEAD keys on them. Modifiable ---------- This mode works in exactly the same way as the above 'Deadkeys', except that it allows you to select which keys are MODIFIABLE. Note that I have imposed an arbitrary limit of 256 modifiable keys in any one keymap, but I doubt that you would ever need anything like this figure. Keymap ------ This is the mode you will probably most often use; it allows you to redefine what each key outputs when pressed. Since this bit is quite complex, I'll split it into several sections. Click on the qualifiers and a key to select which key you want to edit. The selected key will appear highlighted (ie yellow lettering on a black background), and the cursor in the string gadget below the keyboard will activate. If you now type something, it will appear in this gadget (since it is just an Intuition string gadget you can also just click inside it to re-activate it). There are various types of keys in a keymap (as detailed previously) so I shall explain how the editing fuctions affect each one: Deadkeys - Since deadkeys do not output anything themselves but change the output of other keys, you cannot edit a deadkey and so such keys are ghosted in this mode. However they are used in conjuction with modifiable keys (see section below). Since physical keys with deadkeys on them may also have keys that work normally (eg Alt-f is a deadkey; Shift-f and f just work as normal) such keys (eg f) can be edited as detailed below with the restriction that such keys may NOT have strings on them. Ordinary keys - This is the majority of keys, which have no special features (eg deadkeys). When you click on such a key, the character output by this key will appear in the little box to the left of the string gadget below the keymap. If you enter a single character into the string gadget, then this will become the character output by the selected key, and the picture of the keymap will change to reflect this. As not all combinations of qualifier and physical key can be uniquely redefined, at certain times (especially if you edit a key with the Control qualifier (eg Control-q)) a requester will appear telling you that some definitions will have to be lost in order to allow your editing, and giving you the option of aborting or letting EditKeys remove some of the other definitions on that physical key. Futhermore, the combination of Shift-Alt-Control-key cannot be defined at all for ordinary keys. If you try this EditKeys will tell you that this is not possible. If you enter more than one character into the string gadget, EditKeys will convert that key into a STRING type key (see below). Modifiable keys - Modifiable keys (eg a) can have their output modified by deadkeys (eg Alt-f followed by a produces á). Such keys can be edited as above except that strings are not permissible on such keys, thus you can redefine what 'a' outputs. But what if you want to redefine what Alt-f followed by 'a' outputs? If you double click the right mouse button, a requester titled 'Select deadkey' will appear. This allows you to choose a deadkey to be used in editing modifiable keys. The requester has gadgets to accept the current deadkey, quit without changing anything, or clearing the current deadkey. To select a deadkey simply type it in at the keyboard (eg hold down Alt and press f). The text 'A-f' will appear in the box. Enter another deadkey if you want to change or press the 'Clear' gadget if you don't want to use a deadkey anymore, then click 'Use this deadkey'. The name of the deadkey (eg A-f (which is short for Alt-f)) will now appear in the far left box at the bottom of the EditKeys window. Now click on a modifiable key (eg a) and the character output by the combination of the selected deadkey and the selected modifiable key will appear in the box to the left of the string gadget (if you are using my example an 'á' will appear there). Now when you enter a character into the string gadget will edit what is output by the combination of the selected deadkey and the selected modifiable key. Try it - it is fairly obvious once you're used to it. String keys - Lastly, string keys. If you click on a string key (or change an ordinary key into one by entering more than one character into the string gadget) then the box to the left of the string gadget turns yellow. String keys may be edited in the normal way, except that you may enter up to 32 characters to be output by each key (Some keymaps seem to have more than this, but the RKM seems to suggest 32 is the safe limit for the console buffer, so 32 it is). Note that string keys are usually displayed by EditKeys on its picture of the keymap as the letters 'STR' where possible (eg 'Help' is a string key but it always appears as 'Help' in the little picture as this looks neater). If you edit a physical key with strings on it so that each string is only one character, EditKeys will give you the option of converting that physical key back to an ordinary key (which saves memory). As usual, EditKeys may have to remove some definitions to accomodate this; a requester will appear to warn you if this is the case. Note that if at any time you want to put a carriage return in a string, click on the 'Return' gadget (shaped like the arrow on the Return key, to the right of the <CSI> gadget). Depending on the AmigaDOS version being used, a little square box or a reversed 'M' will be added onto the end of the string in the string gadget. This is useful for eg. putting common CLI commands on function keys. Thus, if you put list* (where * represents the return character) on F1, then with this keymap in use, pressing F1 will send a list command to the CLI as if you had typed it in and pressed <RETURN>. There is one further point - to the right of the string gadget is a gadget marked <CSI>. What does this mean? Well, if you click a key such as F1 (with a standard CBM keymap loaded), you will get something like *0~ where * is a little square box. This box is used for characters that are not specifically defined for that font, and in this case the character is $9B hex, which is known as the 'Control Sequence Inducer', or CSI for short. A CSI is used to indicate that what follows is not to be output directly but is to be interpreted by the Amiga to eg. change the text colour etc. There are too many sequences to document here (they are in the RKM under 'console.device'). Since you can't enter a CSI directly, clicking on the <CSI> gadget will add a CSI to the current string in the string gadget. The CSI may be the single character $9B, or the two character sequence $1B followed by $5B (<Esc>[). The former is used eg. in keymaps to define function keys, while the latter is used eg. in 'Echo' statements to change the text colour. The type of CSI provided by the <CSI> gadget is determined in the 'Options' menu (See the section below on the menus). The Menus --------- The remaining functions of EditKeys are accessed through the pull-down menus. Under AmigaDOS2 or higher, help is available by highlighting a menu item with the right mouse button, then pressing the 'Help' key. The menu items available are: Project Menu ------------ New - Completely clears all information from EditKeys, so allowing you to create a keymap completely from scratch (but believe me, it's easier to edit an existing one). Load - A file requester appears to allow you to select a keymap to load in. Note that the keymap does not have to be in DEVS:keymaps/ for to you to be able to load it in. Save - Saves the current keymap. The keymap is saved to the name of the keymap last loaded. Note that any previous keymap of the same name is overwritten (so be carefull!). Save As - A file requester appears to allow you to select the filename that you wish the current keymap to be saved to. Again, you do not need to save to the DEVS:keymaps/ directory, but if you don't, you won't be able to load the keymap into the system without using the supplied 'LoadKeymap'. Test - A window opens into which you can type. The keymap for this window is that currently being edited by EditKeys, giving a much easier way to test your new keymap than messing around with SetMap etc. To close this window type 'quit' on a new line. Make sure your keymap has 'q','u','i', and 't' defined else you cannot quit without going back into EditKeys and defining these keys somewhere. This window is asynchronous to the main window, which still accepts input while the test window is open. If you reselect the 'Test' option with the window active, then the keymap in the test window is updated to that currently in EditKeys. Put Char - A requester appears into which you can input the decimal value of any character, which is then added to the main string gadget. This is very useful for adding characters which are not mapped onto the current keymap. About - Guess. Sleep - Since the EditKeys window is rather large, you can use this option to shrink EditKeys out of the way. Under AmigaDOS 1.3, EditKeys opens a tiny window with just one gadget in it. Click on this gadget to make EditKeys reopen its main window and resume normal operations. Under AmigaDOS2+, this option closes the main EditKeys window and adds an 'EditKeys' menu item to the Workbench Tools menu. If you select this item EditKeys will restart. Quit - Guess... A requester checks that you are sure before quiting (Any unsaved keymaps will be lost if you quit!). Options Menu ------------ This menu allows you to alter certain aspects of EditKeys operation. The available switches are: One char. CSI - These two options are mutually exclusive and control the Two char. CSI type of CSI produced by the <CSI> gadget. See the text about the <CSI> gadget in the 'Keymap' section above. Create Icons? - Under AmigaDOS 2.1 and higher keymaps now have icons. If this switch is enabled then the 'Save As' command will also write out an icon to accompany the keymap, if the keymap does not already have an icon. The icon is the standard system icon for keymaps. This option is off by default. Well, I think that's it. I think (hope!) the program is easier to use than this file is to understand, so just use EditKeys and all should become clear. If for any reason you want to contact me about EditKeys, I can be contacted via Internet Email: kinder@teaching.physics.ox.ac.uk david.kinder@physics.ox.ac.uk Postal mail: 2, Clwtt Cottages, Bangor Road, Gyfelia, Nr. Wrexham, Clwyd, LL13 0YL. ENGLAND. Thanks to --------- In no particular order: HiSoft, Commodore, Oriel, Pink Floyd, The Sisters of Mercy, Curve, and NIN. History (² only applies to AmigaDOS2 or higher.) ------- (³ only applies to AmigaDOS3 or higher.) v1.0 First release. v1.1 ² Improved appearance under AmigaDOS2. v1.2 Renamed 'Iconify' menu option to 'Sleep' to reflect that with AmigaDOS2+ 'Sleep' closes EditKeys down to an item in the Workbench Tools menu. ² Removed need for 'arp.library' under AmigaDOS2+. v1.3 Added 'Return' gadget. Modified 'Project' menu; the shortcut for 'Sleep' is now Right-Amiga-Z (Zzz...). EditKeys now behaves itself if the default font is not topaz/8. Added 'CSI Type' menu, <CSI> gadget now produces both types of CSI. ² Program now quits with an explanation if 'asl.library' is not available. ² Improved 'Sleep'; if Workbench is not loaded then EditKeys opens a small window as for AmigaDOS 1.3. ² Corrected argument parser routine. ² EditKeys window now has a zoom gadget. ² Menu help implemented. v1.4 New 'Project' menu option - 'Test'. Changed 'CSI Type' menu to 'Options', and added new switch to the menu - 'Create Icons'. ² If Workbench not loaded 'Sleep' shrinks EditKeys to zoomed state. ² Menu help for menu headers. ² Yes/No requesters now use screen font. ³ Menus have correct new look. v1.5 ² Menu help and file requesters work with zoom gadget. ² Menus improved slightly. If EditKeys is not sure if a file is really a keymap, you are prompted to make sure that you want to load the file. v1.6 If 'Create Icons' is selected, a new icon will only be written if one does not currently exist. New 'Project' menu option - 'PutChar'. v1.61 Removed Enforcer hit. v1.62 Removed more Enforcer hits which occured if there was an error while loading a keymap at startup. v1.63 ³ Gadgets are ghosted with the correct colours for AmigaDOS3+. ² Menu help text corrected. Changed initial window position. "Rise and Reverberate"